home *** CD-ROM | disk | FTP | other *** search
/ Mac Magazin/MacEasy 43 / Mac Magazin and MacEasy Magazine CD - Issue 43.iso / Software / Mobiles Büro / Newton / Newton Entwickler / DIL 2.0 Sample Code ƒ / CompNRun-1 / README.CompNRun < prev   
Text File  |  1997-09-26  |  3KB  |  65 lines
  1. /*
  2. **      Newton Developer Technical Support Sample Code
  3. **
  4. **      CompNRun, a stream file used as a protocol extension by the PDILs
  5. **
  6. **      by David Fedor, Newton Developer Technical Support
  7. **
  8. **      Copyright © 1997 Apple Computer, Inc.  All rights reserved.
  9. **
  10. **      You may incorporate this sample code into your applications without
  11. **      restriction.  This sample code has been provided "AS IS" and the
  12. **      responsibility for its operation is 100% yours.  You are not
  13. **      permitted to modify and redistribute the source as "DTS Sample Code."
  14. **      If you are going to re-distribute the source, we require that you
  15. **      make it clear in the source that the code was descended from
  16. **      Apple-provided sample code, but that you've made changes.
  17. */
  18.  
  19.  
  20. This sample project creates a stream file containing a protocol extension,
  21. which is to be downloaded and executed by a PDIL application.  (See the sample
  22. "SuiteP" to see it in action.)
  23.  
  24. A protocol extension is a NewtonScript function that the PDILs download from a
  25. desktop system.  It can be repeatedly called by the desktop, and executes on
  26. the Newton device.  The calling PDIL application can specify parameters that
  27. the protocol extension can access by sending the message ReadCommandData() to
  28. the extension's argument.
  29.  
  30. This protocol extension, CompNRun, compiles and runs NewtonScript code which
  31. the desktop sends as a parameter, and sends the return value back to the
  32. desktop.  There are actually three steps in the process: the NewtonScript code
  33. is first compiled, and then evaluated.  Then, if the NewtonScript evaluates to
  34. a function, the desktop can optionally specify arguments to call it with.  If
  35. no arguments are specified, the compiled function object will be returned to
  36. the desktop.
  37.  
  38. Most of the time, CompNRun would be used to compile and evaluate a
  39. NewtonScript expression, such as "getroot().foo exists" or other such commands
  40. which aren't simple global function calls.  More complex code could, for
  41. example, perform a complex query on a union soup, create a summary of the
  42. entries and send that summary to the desktop caller.  Doing that operation
  43. locally on the Newton device would be considerably faster than sending all the
  44. data to the desktop.
  45.  
  46. CompNRun takes a frame as its parameter.  The frame must contain a "src" slot,
  47. which is the NewtonScript source that is to be compiled and executed.  If an
  48. "args" slot exists, then the result of the evaluated NewtonScript will be
  49. called as a function.  If there is a non-nil "debug" slot, and an exception is
  50. thrown, then CurrentException() will be called and its result sent back to the
  51. desktop.  (Note that depending on the exception, this might be a large amount
  52. of data, so use this carefully.)
  53.  
  54. The result sent back to the desktop will be an array with two elements.  The
  55. first is status - NIL indicates success, where values of 0, 1 and 2 indicate
  56. that the exception was thrown during the compile, evaluation or calling phase
  57. respectively.  The second element of the result array is the result of
  58. evaluating the NewtonScript, or else the return value of the compiled function
  59. (if the "args" slot was present.)
  60.  
  61. Also included in CompNRun is some NewtonScript code that can be evaluated
  62. locally inside NTK to help convert the stream file into a form that makes it
  63. easy to add to a desktop C application.  See CompNRun.txt for more
  64. information.
  65.